![Introducing Enhanced Alert Actions and Triage Functionality](https://cdn.sanity.io/images/cgdhsj6q/production/fe71306d515f85de6139b46745ea7180362324f0-2530x946.png?w=800&fit=max&auto=format)
Product
Introducing Enhanced Alert Actions and Triage Functionality
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
@mrmlnc/readdir-enhanced
Advanced tools
Package description
The @mrmlnc/readdir-enhanced npm package is a Node.js library that provides a powerful and flexible way to read the contents of a directory. It allows for synchronous and asynchronous directory reading, with the ability to filter, map, and reduce the results. It can also recursively read subdirectories and stream directory entries for efficient processing of large directories.
Asynchronous directory reading
Reads the contents of a directory asynchronously and returns a promise that resolves with an array of filenames.
const readdir = require('@mrmlnc/readdir-enhanced');
readdir.async('path/to/dir').then(files => {
console.log(files);
});
Synchronous directory reading
Reads the contents of a directory synchronously and returns an array of filenames.
const readdir = require('@mrmlnc/readdir-enhanced');
const files = readdir.sync('path/to/dir');
console.log(files);
Recursive directory reading
Reads the contents of a directory and all its subdirectories recursively.
const readdir = require('@mrmlnc/readdir-enhanced');
readdir.async('path/to/dir', { deep: true }).then(files => {
console.log(files);
});
Streaming directory entries
Streams directory entries as they are read, which is useful for efficiently processing large directories.
const readdir = require('@mrmlnc/readdir-enhanced');
const stream = readdir.stream('path/to/dir');
stream.on('data', entry => {
console.log(entry);
});
Filtering directory entries
Filters the directory entries based on a function that receives file stats, allowing for selective reading of the directory contents.
const readdir = require('@mrmlnc/readdir-enhanced');
readdir.async('path/to/dir', { filter: stats => stats.isFile() }).then(files => {
console.log(files);
});
fs-extra is a package that builds on the native fs module, providing additional methods and functionality. It includes methods for recursive directory reading similar to @mrmlnc/readdir-enhanced but also offers a wider range of file system operations, such as copying and moving files.
glob is a package that allows pattern matching for filenames. It can be used to read directories and subdirectories using glob patterns, which is a different approach compared to @mrmlnc/readdir-enhanced's filtering and mapping capabilities.
readdirp is another package that provides recursive directory reading with a stream interface. It is similar to @mrmlnc/readdir-enhanced in its ability to stream directory entries, but it also offers a more fluent API for filtering and setting other options.
Readme
fs.readdir()
:warning: This is «fork» for original
readdir-enhanced
package but with some monkey fixes.
readdir-enhanced
is a backward-compatible drop-in replacement for fs.readdir()
and fs.readdirSync()
with tons of extra features (filtering, recursion, absolute paths, stats, and more) as well as additional APIs for Promises, Streams, and EventEmitters.
readdir-enhanced
has multiple APIs, so you can pick whichever one you prefer. There are three main APIs:
Synchronous API
aliases: readdir.sync
, readdir.readdirSync
Blocks the thread until all directory contents are read, and then returns all the results.
Async API
aliases: readdir
, readdir.async
, readdir.readdirAsync
Reads the starting directory contents asynchronously and buffers all the results until all contents have been read. Supports callback or Promise syntax (see example below).
Streaming API
aliases: readdir.stream
, readdir.readdirStream
The streaming API reads the starting directory asynchronously and returns the results in real-time as they are read. The results can be piped to other Node.js streams, or you can listen for specific events via the EventEmitter interface. (see example below)
var readdir = require('readdir-enhanced');
var through2 = require('through2');
// Synchronous API
var files = readdir.sync('my/directory');
// Callback API
readdir.async('my/directory', function(err, files) { ... });
// Promises API
readdir.async('my/directory')
.then(function(files) { ... })
.catch(function(err) { ... });
// EventEmitter API
readdir.stream('my/directory')
.on('data', function(path) { ... })
.on('file', function(path) { ... })
.on('directory', function(path) { ... })
.on('symlink', function(path) { ... })
.on('error', function(err) { ... });
// Streaming API
var stream = readdir.stream('my/directory')
.pipe(through2.obj(function(data, enc, next) {
console.log(data);
this.push(data);
next();
});
readdir-enhanced
adds several features to the built-in fs.readdir()
function. All of the enhanced features are opt-in, which makes readdir-enhanced
fully backward compatible by default. You can enable any of the features by passing-in an options
argument as the second parameter.
By default, readdir-enhanced
will only return the top-level contents of the starting directory. But you can set the deep
option to recursively traverse the subdirectories and return their contents as well.
The deep
option can be set to true
to traverse the entire directory structure.
var readdir = require('readdir-enhanced');
readdir('my/directory', {deep: true}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1/file.txt
// => subdir1/subdir2
// => subdir1/subdir2/file.txt
// => subdir1/subdir2/subdir3
// => subdir1/subdir2/subdir3/file.txt
});
The deep
option can be set to a number to only traverse that many levels deep. For example, calling readdir('my/directory', {deep: 2})
will return subdir1/file.txt
and subdir1/subdir2/file.txt
, but it won't return subdir1/subdir2/subdir3/file.txt
.
var readdir = require('readdir-enhanced');
readdir('my/directory', {deep: 2}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1/file.txt
// => subdir1/subdir2
// => subdir1/subdir2/file.txt
// => subdir1/subdir2/subdir3
});
For simple use-cases, you can use a regular expression or a glob pattern to crawl only the directories whose path matches the pattern. The path is relative to the starting directory by default, but you can customize this via options.basePath
.
NOTE: Glob patterns always use forward-slashes, even on Windows. This does not apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using
[\\/]
.
var readdir = require('readdir-enhanced');
// Only crawl the "lib" and "bin" subdirectories
// (notice that the "node_modules" subdirectory does NOT get crawled)
readdir('my/directory', {deep: /lib|bin/}, function(err, files) {
console.log(files);
// => bin
// => bin/cli.js
// => lib
// => lib/index.js
// => node_modules
// => package.json
});
For more advanced recursion, you can set the deep
option to a function that accepts an fs.Stats
object and returns a truthy value if the starting directory should be crawled.
NOTE: The
fs.Stats
object that's passed to the function has additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
var readdir = require('readdir-enhanced');
// Crawl all subdirectories, except "node_modules"
function ignoreNodeModules (stats) {
return stats.path.indexOf('node_modules') === -1;
}
readdir('my/directory', {deep: ignoreNodeModules}, function(err, files) {
console.log(files);
// => bin
// => bin/cli.js
// => lib
// => lib/index.js
// => node_modules
// => package.json
});
The filter
option lets you limit the results based on any criteria you want.
For simple use-cases, you can use a regular expression or a glob pattern to filter items by their path. The path is relative to the starting directory by default, but you can customize this via options.basePath
.
NOTE: Glob patterns always use forward-slashes, even on Windows. This does not apply to regular expressions though. Regular expressions should use the appropraite path separator for the environment. Or, you can match both types of separators using
[\\/]
.
var readdir = require('readdir-enhanced');
// Find all .txt files
readdir('my/directory', {filter: '*.txt'});
// Find all package.json files
readdir('my/directory', {filter: '**/package.json', deep: true});
// Find everything with at least one number in the name
readdir('my/directory', {filter: /\d+/});
For more advanced filtering, you can specify a filter function that accepts an fs.Stats
object and returns a truthy value if the item should be included in the results.
NOTE: The
fs.Stats
object that's passed to the filter function has additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
var readdir = require('readdir-enhanced');
// Only return file names containing an underscore
function myFilter(stats) {
return stats.isFile() && stats.path.indexOf('_') >= 0;
}
readdir('my/directory', {filter: myFilter}, function(err, files) {
console.log(files);
// => __myFile.txt
// => my_other_file.txt
// => img_1.jpg
// => node_modules
});
By default all readdir-enhanced
functions return paths that are relative to the starting directory. But you can use the basePath
option to customize this. The basePath
will be prepended to all of the returned paths. One common use-case for this is to set basePath
to the absolute path of the starting directory, so that all of the returned paths will be absolute.
var readdir = require('readdir-enhanced');
var path = require('path');
// Get absolute paths
var absPath = path.resolve('my/dir');
readdir('my/directory', {basePath: absPath}, function(err, files) {
console.log(files);
// => /absolute/path/to/my/directory/file1.txt
// => /absolute/path/to/my/directory/file2.txt
// => /absolute/path/to/my/directory/subdir
});
// Get paths relative to the working directory
readdir('my/directory', {basePath: 'my/directory'}, function(err, files) {
console.log(files);
// => my/directory/file1.txt
// => my/directory/file2.txt
// => my/directory/subdir
});
By default, readdir-enhanced
uses the correct path separator for your OS (\
on Windows, /
on Linux & MacOS). But you can set the sep
option to any separator character(s) that you want to use instead. This is usually used to ensure consistent path separators across different OSes.
var readdir = require('readdir-enhanced');
// Always use Windows path separators
readdir('my/directory', {sep: '\\', deep: true}, function(err, files) {
console.log(files);
// => subdir1
// => subdir1\file.txt
// => subdir1\subdir2
// => subdir1\subdir2\file.txt
// => subdir1\subdir2\subdir3
// => subdir1\subdir2\subdir3\file.txt
});
By default, readdir-enhanced
uses the default Node.js FileSystem module for methods like fs.stat
, fs.readdir
and fs.lstat
. But in some situations, you can want to use your own FS methods (FTP, SSH, remote drive and etc). So you can provide your own implementation of FS methods by setting options.fs
or specific methods, such as options.fs.stat
.
var readdir = require('readdir-enhanced');
function myCustomReaddirMethod(dir, callback) {
callback(null, ['__myFile.txt']);
}
var options = {
fs: {
readdir: myCustomReaddirMethod
}
};
readdir('my/directory', options, function(err, files) {
console.log(files);
// => __myFile.txt
});
fs.Stats
objects instead of stringsAll of the readdir-enhanced
functions listed above return an array of strings (paths). But in some situations, the path isn't enough information. So, readdir-enhanced
provides alternative versions of each function, which return an array of fs.Stats
objects instead of strings. The fs.Stats
object contains all sorts of useful information, such as the size, the creation date/time, and helper methods such as isFile()
, isDirectory()
, isSymbolicLink()
, etc.
NOTE: The
fs.Stats
objects that are returned also have additionalpath
anddepth
properties. Thepath
is relative to the starting directory by default, but you can customize this viaoptions.basePath
. Thedepth
is the number of subdirectories beneath the base path (seeoptions.deep
).
To get fs.Stats
objects instead of strings, just add the word "Stat" to the function name. As with the normal functions, each one is aliased (e.g. readdir.async.stat
is the same as readdir.readdirAsyncStat
), so you can use whichever naming style you prefer.
var readdir = require('readdir-enhanced');
// Synchronous API
var stats = readdir.sync.stat('my/directory');
var stats = readdir.readdirSyncStat('my/directory');
// Async API
readdir.async.stat('my/directory', function(err, stats) { ... });
readdir.readdirAsyncStat('my/directory', function(err, stats) { ... });
// Streaming API
readdir.stream.stat('my/directory')
.on('data', function(stat) { ... })
.on('file', function(stat) { ... })
.on('directory', function(stat) { ... })
.on('symlink', function(stat) { ... });
readdir.readdirStreamStat('my/directory')
.on('data', function(stat) { ... })
.on('file', function(stat) { ... })
.on('directory', function(stat) { ... })
.on('symlink', function(stat) { ... });
readdir-enhanced
is fully backward-compatible with Node.js' built-in fs.readdir()
and fs.readdirSync()
functions, so you can use it as a drop-in replacement in existing projects without affecting existing functionality, while still being able to use the enhanced features as needed.
var readdir = require('readdir-enhanced');
var readdirSync = readdir.sync;
// Use it just like Node's built-in fs.readdir function
readdir('my/directory', function(err, files) { ... });
// Use it just like Node's built-in fs.readdirSync function
var files = readdirSync('my/directory');
I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.
To build the project locally on your computer:
Clone this repo
git clone https://github.com/bigstickcarpet/readdir-enhanced.git
Install dependencies
npm install
Run the tests
npm test
readdir-enhanced
is 100% free and open-source, under the MIT license. Use it however you want.
FAQs
fs.readdir with sync, async, and streaming APIs + filtering, recursion, absolute paths, etc.
The npm package @mrmlnc/readdir-enhanced receives a total of 2,448,663 weekly downloads. As such, @mrmlnc/readdir-enhanced popularity was classified as popular.
We found that @mrmlnc/readdir-enhanced demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket now supports four distinct alert actions instead of the previous two, and alert triaging allows users to override the actions taken for all individual alerts.
Security News
Polyfill.io has been serving malware for months via its CDN, after the project's open source maintainer sold the service to a company based in China.
Security News
OpenSSF is warning open source maintainers to stay vigilant against reputation farming on GitHub, where users artificially inflate their status by manipulating interactions on closed issues and PRs.